Workbench Add-On/Workbench Add-On - Volume 1.iso/Dev/TileForth/doc/forth.txt

Text File | 1995-08-25 | 46KB | 1,058 lines

          FORTH(3X)                                               FORTH(3X)


          NAME
                 forth   forth-83  standard  word set and tile forth kernel
                 extensions

          SYNOPSIS
                 forth

          DESCRIPTION
                 The required word set of Forth-83 Standard  excluding  the
                 block  file word set and the tile forth kernel extensions.
                 Each  "word"  (function,  procedure,  variable,  etc)   is
                 described  with  its  stack action, parameters, and return
                 values and its code type. The format of the glossary  list
                 is:
                 <type> <name> ( <stack-effect> ) [ <mode> ]
                 The  <stack-effect>  describes  the  parameter  and return
                 values for the word in the following format:
                 ( <arguments> -- <returns>)
                 The arguments and return values are  given  from  left  to
                 right  with  the deepest stack value first. Symbolic names
                 are often used for the arguments while the  return  values
                 are often only described by data type.

                 The optional <mode> may define how the word is interpreted
                 and when it is visible. The  mode  "immediate"  marks  the
                 word  as always executed. The mode "execution" reduces the
                 words visibility to only execution, i.e.,  interpretation,
                 mode.  The mode "compilation" reduces the words visibility
                 to only compilation mode. Last, the mode  "private"  marks
                 the  words  as  only visible in the vocabulary where it is
                 defined. Additional modes are added by  other  tile  forth
                 extensions.

                 The  list  of  required words in the Forth-83 Standard are
                 described   in   the   following   sub-sections;    "Stack
                 Manipulation",  "Memory  Access",  "Logic",  "Arithmetic",
                 "Comparison", "Numeric Conversion", "Control  Structures",
                 "Terminal  Input/Output", "Interpreter", "Vocabulary", and
                 "Defining Words". Each  sub-section  is  sorted  in  ASCII
                 order.

             Stack Manipulation
                 The   Forth-83   Standard   parameter   and  return  stack
                 manipulation  functions.  The  tile  forth   kernel   also
                 supports the double number stack manipulation extension.

                 code -rot ( x y z -- z x y)
                        The  top  three  stack entries are rotated, forcing
                        the top to become the deepest of the three.

                 code 2>r ( x y -- ) compilation
                        Double "to-r". "x" and "y" are transferred  to  the
                        return stack.




                                  September 17, 1990                      1





          FORTH(3X)                                               FORTH(3X)


                 code 2drop ( x y -- )
                        Double "drop". "x" and "y" are dropped.

                 code 2dup ( x1 y1 -- x1 y1 x1 y1)
                        Double "dup". The first pair is copied.

                 code 2over (x1 y1 x2 y2 -- x1 y1 x2 y2 x1 y1)
                        Double "over". The second pair is copied.

                 code 2r> ( -- x y) compilation
                        Double  "from-r".  "x" and "y" are removed from the
                        return stack and transferred to the data stack.

                 code 2rot ( x1 y1 x2 y2 x3 y3 -- x2 y2 x3 y3 x1 y1)
                        Double "rot". The three pairs change places.

                 code 2swap ( x1 y1 x2 y2 -- x2 y2 x1 y1)
                        Double "swap". The two pairs change places.

                 code >r ( x -- ) compilation
                        Transfer "x" to the return stack.

                 code ?dup ( x -- [x x] or [x])
                        Duplicate "x" if it is non-zero.

                 code depth ( -- +n)
                        "+n" is the number of values contained in the  data
                        stack before "+n" was placed on the stack.

                 code drop ( x -- )
                        "x" is removed from the stack.

                 code dup ( x -- x x)
                        Duplicate "x".

                 code nip ( x y -- y)
                        The second stack element "x" is removed.

                 code over ( x y -- x y x)
                        A copy of "x" is made and moved over "y".

                 code pick ( +n -- x)
                        "x"  is  a  copy  of the "+n"-th stack element, not
                        counting "+n" itself. [0..depth-1]
                        "0 pick" is equivalent to "dup"
                        "1 pick" is equivalent to "over"

                 code r> ( -- x) compilation
                        "x"  is  removed  from   the   return   stack   and
                        transferred to the data stack.

                 code r@ ( -- x) compilation
                        "x" is a copy of the top of the return stack.




                                  September 17, 1990                      2





          FORTH(3X)                                               FORTH(3X)


                 code roll ( +n -- )
                        The  "+n"-th  stack value, not counting "+n" itself
                        is first removed and then transferred to the top of
                        the  stack,  moving  the  remaining values into the
                        vacated position. The parameter should  be  in  the
                        interval: [0..depth-1].
                        "0 roll" is a null operation
                        "1 roll" is equivalent to "swap"
                        "2 roll" is equivalent to "rot"

                 code rot ( x y z -- y z x)
                        The  top  three stack entries are rotated, bringing
                        the deepest to the top.

                 code swap ( x y -- y x)
                        The top two stack entries are exchanged.

                 code tuck ( x y -- y x y)
                        A copy of "y" is tucked under "x".

             Memory Access
                 The Forth-83 Standard memory and data access word set. The
                 tile  forth  kernel  extends  the  Forth-83  Standard with
                 additional access functions for bit testing and bit  field
                 access. All access to memory is achieved through this word
                 set.

                 code ! ( 32b addr -- )
                        The postfix assignment  operator.  Store  "32b"  at
                        "addr".

                 code +! ( x1 addr -- )
                        "x1"  is  added  to  the  value at "addr" using the
                        convention for "+". The value at "addr" is  assumed
                        to  be  of  size  "cell".   The  sum  replaces  the
                        original value at "addr".

                 code -match ( addr1 addr2 n -- bool)
                        Matches the strings at address "addr1" and  "addr2"
                        of  length  "n" at the parameter addresses. Returns
                        "false" if the strings are equal  else  "true".  If
                        the  length  "n"  is  zero the function will return
                        "true".

                 code -trailing ( addr +n1 -- addr +n2)
                        The  character  counter  "+n1"  of  a  text  string
                        beginning at "addr" is adjusted to exclude trailing
                        spaces. If "+n1" is zero, then "+n2"  is  zero.  If
                        the entire string consists of spaces, then "+n2" is
                        zero.

                 code <c@ ( addr -- 8b)
                        "8b" is the value at  "addr".  The  value  is  sign
                        extended to the stack (cell) width.



                                  September 17, 1990                      3





          FORTH(3X)                                               FORTH(3X)


                 code <f@ ( x p w -- y)
                        Field  access within a 32-bit quantity. "y" are the
                        bits within "x" at position  "p"  and  with  a  bit
                        field  width,  "w". Bits positions are counted from
                        right to  left  starting  with  zero.  A  field  is
                        defined from a position and upwards. The result "y"
                        is sign extended.

                 code <w@ ( addr -- 16b)
                        "16b" is the value at "addr".  The  value  is  sign
                        extended to the stack (cell) width.

                 code @ ( addr -- 32b)
                        "32b"  is  the  value  at  "addr". Primary variable
                        value access function.

                 code b! ( x y p -- z)
                        Returns "z", the  result  of  setting  the  bit  at
                        position  "p" in "y" according to the value of "x".
                        The bit is set to zero if "x" is zero else one.

                 code b@ ( x p -- y)
                        Returns "true" if the bit a position "p" in "x"  is
                        one else "false".

                 code bounds ( addr1 n -- addr2 addr1)
                        Converts   vector  address  and  size  to  boundary
                        address suitable for a "do"-loop.  "addr2"  is  the
                        end address of the vector, i.e., the sum of "addr1"
                        and "n".

                 code c! ( 8b addr -- )
                        The postfix  assignment  operator.  Store  "8b"  at
                        "addr".

                 code c@ ( addr -- 8b)
                        "8b"  is the value at "addr". The value is not sign
                        extended.

                 code cmove ( addr1 addr2 u -- )
                        Move the "u" bytes at address "addr1"  to  "addr2".
                        The  byte  at  "addr1"  is  moved first, proceeding
                        toward high memory.  If  "u"  is  zero  nothing  is
                        moved.

                 code cmove> ( addr1 addr2 u -- )
                        Move  the  "u" bytes at address "addr1" to "addr2".
                        The   move   begins   by   moving   the   byte   at
                        ("addr1"+"u"-1)  to ("addr2"+"u"-1) and proceeds to
                        successively lower addresses for "u" bytes.  If "u"
                        is  zero  nothing  is  moved.  Useful for sliding a
                        string towards higher addresses.





                                  September 17, 1990                      4





          FORTH(3X)                                               FORTH(3X)


                 code count ( addr1 -- addr2 +n)
                        "addr2" is "addr1"+1 and "+n" is the length of  the
                        counted   string   at  "addr1".  The  byte  "addr1"
                        contains the byte count  "+n".  Range  of  "+n"  is
                        [0..255].

                 code f! ( x y p w -- z)
                        Inserts  the value of "x" into "y" at the bit field
                        which is defined by the position "p" and  with  the
                        width "w". The value "x" is shifted and masked into
                        "y" to form the result "z".

                 code f@ ( x p w -- y)
                        Field access within a 32-bit quantity. "y" are  the
                        bits  within  "x"  at  position  "p" and with a bit
                        field width, "w". Bits positions are  counted  from
                        right  to  left  starting  with  zero.  A  field is
                        defined from a position and upwards.

                 code fill ( addr u 8b -- )
                        "u" bytes of memory beginning at "addr" are set  to
                        "8b".  No action is taken is "u" is zero.

                 code w! ( 16b addr -- )
                        The  postfix  assignment  operator.  Store "16b" at
                        "addr".

                 code w@ ( addr -- 16b)
                        "16b" is the value at "addr". The value is not sign
                        extended.

             Logic
                 The  Forth-83  Standard  logic  functions.  The tile forth
                 kernel  extends  the  basic  function  set  with   boolean
                 constants  and  a  boolean  conversion function. All logic
                 functions manipulate their parameters bit-by-bit.

                 code and ( 32b1 32b2 -- 32b3)
                        "32b3" is the bit-by-bit logical and of "32b1"  and
                        "32b2".

                 code boolean ( n -- bool)
                        Maps  numerical value to a boolean value, "true" or
                        "false".  Non-zero values are mapped to "true"  and
                        zero to "false".

                 constant false ( -- 0)
                        The constant "false" represented by the value zero.

                 code or ( 32b1 32b2 -- 32b3)
                        "32b3" is the  bit-by-bit  inclusive-or  of  "32b1"
                        with "32b2".





                                  September 17, 1990                      5





          FORTH(3X)                                               FORTH(3X)


                 code not ( 32b1 -- 32b2)
                        "32b2" is the one's complements of "32b1".

                 constant true ( -- -1)
                        The  constant "true" represented by the value minus
                        one.

                 code xor ( 32b1 32b2 -- 32b3)
                        "32b3" is the  bit-by-bit  exclusive-or  of  "32b1"
                        with "32b2".

             Arithmetic
                 The  Forth-83 Standard arithmetic word set. The tile forth
                 kernel  extends  the  Forth-83  Standard  with  arithmetic
                 functions  for  shifting and additional numeric constants.
                 Double number width arithmetic function such as  "d+"  and
                 "dnegate"  are  not  implemented as tile forth is a 32-bit
                 implementation. Arithmetic errors are caught by  the  tile
                 forth  kernel and passed to the application as signals. An
                 exception block may be used to catch the signal.

                 code * ( w1 w2 -- w3)
                        "w3"  is  the  least-significant  32  bits  of  the
                        arithmetic product of "w1" times and "w2".

                 code */ ( w1 w2 w3 -- w4)
                        "w1"  is  first  multiplied  by  "w2"  producing an
                        intermediate 32-bit result. "w4" is  the  floor  of
                        the  quotient  of  the  intermediate  32-bit result
                        divided by the divisor "w3". The  product  of  "w1"
                        times  "w2" is maintained as an intermediate 32-bit
                        result for greater  precision  then  the  otherwise
                        equivalent  sequence:  "w1  w2  *  w3  /". An error
                        condition results if the divisor  is  zero  and  an
                        exception is raised.

                 code */mod ( w1 w2 w3 -- w4 w5)
                        "w1"  is  first  multiplied  by  "w2"  producing an
                        intermediate 32-bit result. "w4" is  the  remainder
                        and  "w5"  is  the  floor  of  the  quotient of the
                        intermediate 32-bit result divided by  the  divisor
                        "w3".  A 32-bit intermediate product is used as for
                        "*/". "w4" has the same sign as "w3" or is zero. An
                        error  condition results if the divisor is zero and
                        an exception is raised.

                 code + ( w1 w2 -- w3)
                        "w3" is the arithmetic sum of "w1" and "w2".

                 code - ( w1 w2 -- w3)
                        "w3" is the result of subtracting "w2" from "w1".

                 constant -1 ( -- -1)
                        Constant minus one.



                                  September 17, 1990                      6





          FORTH(3X)                                               FORTH(3X)


                 constant -2 ( -- -2)
                        Constant minus two.

                 constant -4 ( -- -4)
                        Constant minus four.

                 code / ( w1 w2 -- w3)
                        "w3" is the floor of the quotient of  "w1"  divided
                        by  the divisor "w2". An error condition results if
                        the divisor is zero.

                 code /mod ( w1 w2 -- w3 w4)
                        "w3" is the remainder and "w4"  the  floor  of  the
                        quotient  of "w1" divided by the divisor "w2". "w3"
                        has the same sign as "w2"  or  is  zero.  An  error
                        condition  results  if  the  divisor is zero and an
                        exception is raised.

                 constant 0 ( -- 0)
                        Constant zero.

                 constant 1 ( -- 1)
                        Constant one.

                 code 1+ ( w1 -- w2)
                        "w2" is the result of adding one to "w1"  according
                        to the operation of "+".

                 code 1- ( w1 -- w2)
                        "w2"  is  the  result  of  subtracting  one to "w1"
                        according to the operation of "-".

                 constant 2 ( -- 2)
                        Constant two.

                 code 2* ( n1 -- n2)
                        "n2" is the result of arithmetically shifting  "n1"
                        left one bit. The sign is included in the shift and
                        remains unchanged.

                 code 2+ ( w1 -- w2)
                        "w2" is the result of adding two to "w1"  according
                        to the operation of "+".

                 code 2- ( w1 -- w2)
                        "w2"  is  the  result  of  subtracting  two to "w1"
                        according to the operation of "-".

                 code 2/ ( n1 -- n2)
                        "n2" is the result of arithmetically shifting  "n1"
                        right  one  bit.  The sign is included in the shift
                        and remains unchanged.





                                  September 17, 1990                      7





          FORTH(3X)                                               FORTH(3X)


                 constant 4 ( -- 4)
                        Constant four.

                 code << ( n1 n2 -- n3)
                        "n3" is the result of logically shifting "n1"  left
                        "n2" steps.

                 code >> ( n1 n2 -- n3)
                        "n3" is the result of logically shifting "n1" right
                        "n2" steps.

                 code abs ( n -- u)
                        "u" is the absolute value of "n".

                 code max ( n1 n2 -- n3)
                        "n3" is the greater of "n1" and "n2"  according  to
                        the operation of ">".

                 code min ( n1 n2 -- n3)
                        "n3"  is  the  lesser of "n1" and "n2" according to
                        the operation of "<".

                 code mod ( n1 n2 -- n3)
                        "n3"  is  the  remainder  after  dividing  "n1"  by
                        divisor "n2".  "n3" has the same sign as "n2" or is
                        zero. An error condition results if the divisor  is
                        zero  or  if  the  quotient  falls  outside  of the
                        numerical range.

                 code negate ( n1 -- n2)
                        "n2" is the two's complement  of  "n1",  i.e.,  the
                        difference of zero less "n1".

                 constant nil ( -- 0)
                        Constant for a nil pointer.

                 code um* ( u1 u2 -- u3)
                        "u3"  is  the  unsigned product of "u1" times "u2".
                        All values and arithmetic are unsigned.

                 code um/mod ( u1 u2 -- u3 u4)
                        "u3" is the remainder and "u4" is the floor of  the
                        quotient  after  dividing "u1" by the divisor "u2".
                        All values and arithmetic are  unsigned.  An  error
                        condition  results if the divisor is zero or if the
                        quotient lies outside the numerical range.

             Comparison
                 The Forth-83 Standard comparison word set. The tile  forth
                 kernel  extends  the  standard  with an integer range test
                 function.  The kernel does  not  implement  double  number
                 comparison  functions.   Boolean values "true" and "false"
                 are represented with "-1" and "0".




                                  September 17, 1990                      8





          FORTH(3X)                                               FORTH(3X)


                 code 0< ( n -- bool)
                        Returns "true" if "n" is less than zero (negative).

                 code 0= ( w -- bool)
                        Returns "true" if "w" is zero.

                 code 0> ( n -- bool)
                        Returns "true" if "n" is greater than zero.

                 code < ( n1 n2 -- bool)
                        Returns "true" if "n1" is less than "n2".

                 code = ( w1 w2 -- bool)
                        Returns "true" if "w1" is equal to "w2"

                 code > ( n1 n2 -- bool)
                        Returns "true" if "n1" is greater than "n2"

                 code ?within ( value lower upper -- bool)
                        Tests  if the parameter "value" is within the range
                        "lower" to "upper". Returns "true"  if  within  the
                        range else "false".

                 code u< ( u1 u2 -- bool)
                        Returns "true" if "u1" is less than "u2".

             Numeric Conversion
                 The  Forth-83  Standard  numeric conversion functions. The
                 tile forth kernel extends  the  standard  with  string  to
                 number  converter, and general number literal recognition.

                 code # ( +d1 -- +d2 )
                        The remainder of "+d1"  divided  by  the  value  of
                        "base"  is  converted  to  a  ASCII  character  and
                        appended to the output string toward  lower  memory
                        addresses.  "+d2" if the quotient and is maintained
                        for further processing. Typically used between "<#"
                        and "#>".

                 code #> ( x -- addr +n)
                        Pictured   numeric   output   conversion  is  ended
                        dropping  "x".   "addr"  is  the  address  of   the
                        resulting  output  string.   "+n"  is the number of
                        characters in the output string.  "addr"  and  "+n"
                        together are suitable for "type".

                 code #s ( +x -- 0)
                        "+x"   is   converted   appending   each  resultant
                        character into the pictured numeric  output  string
                        until  the  quotient  is  zero.  A  single  zero is
                        appended to the output string  if  the  number  was
                        initially  zero.  Typically  used  between "<#" and
                        "#>".




                                  September 17, 1990                      9





          FORTH(3X)                                               FORTH(3X)


                 code <# ( x -- )
                        Initialize pictured numeric output conversion.  The
                        words:  "<#  #  #s  hold  sign  #>"  can be used to
                        specify the conversion of a number  into  an  ASCII
                        text string stored in right-to-left order.

                 code ?number ( str -- [n true] or [str false]) recognizer
                        Convert a string of character to a number using the
                        current "base".  If the conversion is not  possible
                        the   string   is  returned  with  a  "false"  flag
                        indicating that the conversion failed otherwise the
                        conversion  value, the number, and a "true" flag is
                        returned.

                 variable base ( -- addr)
                        The address of a variable  containing  the  current
                        numeric conversion radix.

                 code binary ( -- )
                        Set  the  input-output numeric conversion "base" to
                        2.

                 code convert ( +d1 addr1 -- +d2 addr2)
                        "+d2" is the result of  converting  the  characters
                        within the text beginning at "addr1"+1 into digits,
                        using the value of "base",  and  accumulating  each
                        into  "+d1" after multiplying "+d1" by the value of
                        "base". Conversion continues until an inconvertible
                        character  is  encountered. "addr2" is the location
                        of the first inconvertible character.

                 code decimal ( -- )
                        Set the input-output numeric conversion  "base"  to
                        10.

                 code hex ( -- )
                        Set  the  input-output numeric conversion "base" to
                        16.

                 code hold ( char -- )
                        "char" is inserted into a pictured  numeric  output
                        string.  Typically used between "<#" and "#>".

                 code octal ( -- )
                        Set  the  input-output numeric conversion "base" to
                        8.

                 code sign ( n -- )
                        If "n" is negative, an ASCII "-"  (minus  sign)  is
                        appended  to  the pictured numerical output string.
                        Typically used between "<#" and "#>".

             Control Structures
                 The Forth-83 Standard control  flow  word  set.  The  tile



                                  September 17, 1990                     10





          FORTH(3X)                                               FORTH(3X)


                 forth  kernel  extends the basic set of control structures
                 with    environment    arguments    access,    conditional
                 compilation,  case  structure, additional loop constructs,
                 and recursion words.

                 code #else ( -- ) immediate
                        Used in the following form:
                        <flag> #if <true-part> #else <else-part> #then
                        Marks  the  beginning  of  a   "else"-part   of   a
                        conditional code section.

                 code #if ( flag -- ) immediate
                        Used in the following form:
                        <flag> #if <true-part> [ #else <false-part> ] #then
                        Marks the beginning of a conditional code  section.
                        The else section is optional.

                 code #ifdef ( -- ) immediate
                        Used  in the following form for testing if a symbol
                        already is available:
                        #ifdef <name> <true-part> [  #else  <false-part>  ]
                        #then
                        If  <name> is available in the current search chain
                        "context" the true section of code is  executed  or
                        compiled  according to mode else the optional false
                        section.

                 code #ifundef ( -- ) immediate
                        Used in the following form:
                        #ifundef <name> <true-part> [ #else <false-part>  ]
                        #then
                        Performs the same function as "#ifdef" but the true
                        section is executed if the symbol is not  available
                        in the current search chain.

                 code #then ( -- ) immediate
                        Used in the following form:
                        <flag> #if <true-part> [ #else <false-part> ] #then
                        Marks the end of a conditional code section.

                 code +loop ( n -- ) immediate compilation
                        "n" is added to the loop index. If  the  new  index
                        was incremented across the boundary between limit-1
                        and limit then the loop is terminated and the  loop
                        control  parameters are discarded. When the loop is
                        not terminated, execution continues to  just  after
                        the  corresponding  "do".  "+loop" is not available
                        outside a colon definition.

                 code ?do ( w1 w2 -- ) immediate compilation
                        Used in the following forms:
                        ?do ...  { i | leave } ...  loop
                        or
                        ?do ...  { i | leave } ...  +loop



                                  September 17, 1990                     11





          FORTH(3X)                                               FORTH(3X)


                        Begins a checked entry loop which terminates  based
                        on  control  parameters.  The  loop index begins at
                        "w2", and terminates based on the limit  "w1".  See
                        "loop"  and  "+loop" for details on how the loop is
                        terminated. If "w1" and "w2"  are  equal  the  loop
                        section is skipped.

                 code abort ( -- )
                        Clears  the data stack and performs the function of
                        "quit".  No message is displayed.

                 code abort" ( flag -- ) immediate compilation
                        Used in the following form:
                        <flag> abort" <abort-message> "
                        When later executed, if "flag" is true the  <abort-
                        message> delimited by close quote, is displayed and
                        then  a  system  dependent  error  abort  sequence,
                        including  the  function  "abort", is performed. If
                        "flag" is false, the flag is dropped and  execution
                        continues.  The  blank following abort" is not part
                        of the <abort-message>.

                 code again ( -- ) immediate compilation
                        Used in the following form to  compile  an  eternal
                        loop:
                        begin ...  again
                        The  loop  construct may only be left by an "abort"
                        or an "exit" word in the code section of the  loop.

                 code argc ( -- num)
                        Returns  the  number  of  arguments passed from the
                        environment.  The first argument is always the name
                        of  the  application:  "forth"  or  the name of the
                        start symbol.

                 code argv ( n -- str)
                        Given an index returns the  corresponding  argument
                        string.  The  "string" vocabulary words may be used
                        for process an argument string.

                 code begin ( -- ) immediate compilation
                        Used in the following forms:
                        begin ...  <flag> while ...  repeat
                        or
                        begin ...  <flag> until
              grotty:t:temp:11317:fatal error: integer expected
          or
                        begin ...  again
                        "begin" marks the start  of  a  word  sequence  for
                        repetitive  execution.  A "begin-while-repeat" loop
                        will repeat until <flag>  is  false.  "begin-until"
                        loop  will  be  repeated  until  <flag> is true and
                        "begin-again" will  repeat  until  "abort"-ed.  The
                        words  after  "until" and "repeat" will be executed
                        when either loop is finished.



                                  September 17, 1990                     12





          FORTH(3X)                                               FORTH(3X)


                 code bye ( -- )
                        Leaves the interaction level and exits to the outer
                        support system (if any).

                 code case ( value -- ) immediate compilation
                        Used in the following form:
                        case <case-structure>  { <default-part> } endcase
                        to  mark  the  beginning  of a case structure which
                        should contain a one or several case statements:
                        <case-value> of <case-part> endof
                        The code section after the  last  case  value  part
                        will  receive "value" as a parameter thus a default
                        behavior is easy implemented. The  default  section
                        may  only  copy  this  value  as  "endcase"  is  an
                        implicit "drop".

                 code do ( w1 w2 -- )     immediate compilation
                        Used in the following forms:
                        do ...  { i | leave } ...  loop
                        or
                        do ...  { i | leave } ...  +loop
                        Begins a loop which  terminates  based  on  control
                        parameters.   The  loop  index  begins at "w2", and
                        terminates based on the limit "w1". See "loop"  and
                        "+loop"  for details on how the loop is terminated.
                        The loop is always executed at least once.

                 code else ( -- ) immediate compilation
                        Used in the following form:
                        <flag> if <true-part> else <false-part> then
                        in a conditional structure to mark the beginning of
                        the  false  section.  This section is executed when
                        the <flag> is "false". The  true  section  is  then
                        skipped.

                 code endcase ( -- ) immediate compilation
                        Used in the following form:
                        case <case-structure>  { <default-part> } endcase
                        to mark the end of a case structure.

                 code endof ( -- ) immediate compilation
                        Used in the following form:
                        <case-value> of <case-part> endof
                        to mark the end of a cast value structure.

                 code execute ( addr -- )
                        The   word   definition   indicated  by  "addr"  is
                        executed. An error condition exists  if  "addr"  is
                        not a compilation address.

                 code exit ( -- ) compilation
                        Compiled  within  a colon definition such that when
                        executed, the colon definition returns  control  to
                        the   definition  that  passed  control  to  it  by



                                  September 17, 1990                     13





          FORTH(3X)                                               FORTH(3X)


                        returning control to the return point on the top of
                        the  return stack. An error condition exists if the
                        top of the return stack does not  contain  a  valid
                        return point. May not be used within a "do-loop" or
                        "do-+loop" or an "exception"-block.

                 code i ( -- w) compilation
                        "w" is a copy of the current loop index.  May  only
                        be used in the form:
                        do ...  { i | leave } ...  loop
                        or
                        do ...  { i | leave } ...  +loop
                        "i"  is  not  visible  outside  a colon definition,
                        i.e., when text interpreting  and  should  only  be
                        used within a loop-block.

                 code if ( flag -- ) immediate compilation
                        Used in the following form:
                        <flag> if <true-part> [ else <else-part> ] then
                        If  "flag"  is  true,  the words following "if" are
                        executed and the words following "else" until  just
                        after  "then"  are  skipped.  The  "else"  part  is
                        optional. If  "flag"  is  false,  words  from  "if"
                        through  "else",  or from "if" through "then" (when
                        no "else" is used) are skipped.

                 code j ( -- w) compilation
                        "w" is a copy of the index of the next outer  loop.
                        May  only  be  used  within  a  nested "do-loop" or
                        "do-+loop" in the form:
                        do ...  do ...  { i | j | leave  }  ...   loop  ...
                        loop
                        "j"  is  not  visible  outside  a colon definition,
                        i.e., when text interpreting.

                 code leave ( -- ) compilation
                        Transfers execution to just beyond the next  "loop"
                        or  "+loop".   The  loop is terminated and the loop
                        control parameters are discarded. May only be  used
                        in the following forms:
                        do ...  { i | leave } ...  loop
                        or
                        do ...  { i | leave } ...  +loop
                        "leave"  may appear within other control structures
                        which are nested within  the  "do-loop"  structure.
                        More  than one "leave" may appear within a do-loop.

                 code loop ( -- ) immediate compilation
                        Increments the "do-loop" index by one. If  the  new
                        index  was  incremented across the boundary between
                        limit-1 and limit the loop is  terminated  and  the
                        loop  control  parameters  are  discarded. When the
                        loop is not terminated, execution continues to just
                        after the corresponding "do".



                                  September 17, 1990                     14





          FORTH(3X)                                               FORTH(3X)


                 code of ( value -- ) immediate compilation
                        Used in the following form:
                        <case-value> of <case-part> endof
                        within a case structure to define a value case.

                 code quit ( -- )
                        Clears  the  return  stack,  sets  interpret state,
                        accepts new input from the  current  input  device,
                        and  begins  text  interpretation.  No  messages is
                        displayed.

                 code recurse ( -- ) immediate compilation
                        Used within a definition to make a  recursive  call
                        to the current definition.

                 code repeat ( -- ) immediate compilation
                        Used in the following form:
                        begin ...  <flag> while ...  repeat
                        At  execution-time, "repeat" continues execution to
                        just after the corresponding "begin".

                 code tail-recurse ( -- ) immediate compilation
                        Used within a definition to create a recursive call
                        to  the  current  definition  without saving return
                        status. This is  an  efficient  way  of  generating
                        iterative  forms  as  tail  recursive  calls may be
                        performed any number of times within  a  definition
                        and corresponds to a branch to the beginning of the
                        definition.

                 code then ( -- ) immediate compilation
                        Used in the following form:
                        <flag> if <true-part> [ else <else-part> ] then
                        Marks the end of a conditional statement  "if-else-
                        then".

                 code until ( flag -- ) immediate compilation
                        Used in the following form:
                        begin ...  <flag> until
                        Marks  the  end  of a "begin-until" loop which will
                        terminate based on "flag". If "flag" is  true,  the
                        loop  is terminated.  If "flag" is false, execution
                        continues to just after the corresponding  "begin".

                 code while ( flag -- ) immediate compilation
                        Used in the following form:
                        begin ...  <flag> while ...  repeat
                        Selects conditional execution based on "flag". When
                        "flag" is true, execution continues to  just  after
                        the  "while"  through  to  the  "repeat" which then
                        continues execution to just after the "begin". When
                        "flag"  is false, execution continues to just after
                        the "repeat", exiting the control structure.




                                  September 17, 1990                     15





          FORTH(3X)                                               FORTH(3X)


             Terminal Input/Output
                 The Forth-83 Standard terminal interaction functions.  The
                 tile  forth  kernel  extends  the  basic  set of input and
                 output functions with field format output  and  access  of
                 the  current  input  source file name and the current line
                 number count.

                 code . ( n -- )
                        The absolute value of "n" is displayed  in  a  free
                        field  format  with  a leading minus sign if "n" is
                        negative. A space is emit after the number.

                 code ." ( -- ) immediate compilation
                        Used  in  the  following   form   within   a   code
                        definition:
                        <output-string> "
                        Later   execution   will   display  the  characters
                        <output-string>  up  to  but  but   including   the
                        delimiter  (close-quote).  The  blank following the
                        "." " is not part of the  <output-string>  but  the
                        word separator.

                 code .( ( -- ) immediate
                        Used in the following form:
                        .( <output-comment> )
                        The  characters  <output-comment>  up  to  but  not
                        including the delimiter  (closing-parenthesis)  are
                        displayed.  The blank following ".(" is not part of
                        the <output-comment>.

                 code .s ( -- )
                        Displays the current parameter  stack  contents  in
                        the format:
                        [ <depth> ] <bottom> \ ... \ <top>

                 code ascii ( -- char) immediate
                        Used in the following form:
                        ascii <character> ( -- char)
                        to create a character literal.

                 code cr ( -- )
                        Emits  ASCII  characters  carriage-return and line-
                        feed.

                 code emit ( x -- )
                        The  least-significant  7-bit  ASCII  character  is
                        displayed.

                 code expect ( addr +n -- )
                        Receive  characters and store each into memory.